home *** CD-ROM | disk | FTP | other *** search
/ Total Network Tools 2002 / NextStepPublishing-TotalNetworkTools2002-Win95.iso / Archive / Web Server / PHP.EXE / pear / PEAR.php.in < prev    next >
Encoding:
Text File  |  2001-03-10  |  17.0 KB  |  537 lines
  1. <?php
  2. //
  3. // +----------------------------------------------------------------------+
  4. // | PHP version 4.0                                                      |
  5. // +----------------------------------------------------------------------+
  6. // | Copyright (c) 1997-2001 The PHP Group                                |
  7. // +----------------------------------------------------------------------+
  8. // | This source file is subject to version 2.0 of the PHP license,       |
  9. // | that is bundled with this package in the file LICENSE, and is        |
  10. // | available at through the world-wide-web at                           |
  11. // | http://www.php.net/license/2_02.txt.                                 |
  12. // | If you did not receive a copy of the PHP license and are unable to   |
  13. // | obtain it through the world-wide-web, please send a note to          |
  14. // | license@php.net so we can mail you a copy immediately.               |
  15. // +----------------------------------------------------------------------+
  16. // | Authors: Sterling Hughes <sterling@php.net>                          |
  17. // |          Stig Bakken <ssb@fast.no>                                   |
  18. // +----------------------------------------------------------------------+
  19. //
  20. // $Id: PEAR.php.in,v 1.15 2001/03/10 09:59:15 ssb Exp $
  21. //
  22.  
  23. define('PEAR_ERROR_RETURN', 1);
  24. define('PEAR_ERROR_PRINT', 2);
  25. define('PEAR_ERROR_TRIGGER', 4);
  26. define('PEAR_ERROR_DIE', 8);
  27. define('PEAR_ERROR_CALLBACK', 16);
  28.  
  29. define('PHP_BINDIR', '@prefix@/bin');
  30. define('PEAR_INSTALL_DIR', '@PEAR_INSTALLDIR@');
  31. define('PEAR_EXTENSION_DIR', '@EXTENSION_DIR@');
  32.  
  33. $_PEAR_default_error_mode = PEAR_ERROR_RETURN;
  34. $_PEAR_default_error_options = E_USER_NOTICE;
  35. $_PEAR_default_error_callback = '';
  36. $_PEAR_destructor_object_list = array();
  37.  
  38. //
  39. // Tests needed: - PEAR inheritance
  40. //               - destructors
  41. //
  42.  
  43. /**
  44.  * Base class for other PEAR classes.  Provides rudimentary
  45.  * emulation of destructors.
  46.  *
  47.  * If you want a destructor in your class, inherit PEAR and make a
  48.  * destructor method called _yourclassname (same name as the
  49.  * constructor, but with a "_" prefix).  Also, in your constructor you
  50.  * have to call the PEAR constructor: <code>$this->PEAR();</code>.
  51.  * The destructor method will be called without parameters.  Note that
  52.  * at in some SAPI implementations (such as Apache), any output during
  53.  * the request shutdown (in which destructors are called) seems to be
  54.  * discarded.  If you need to get any debug information from your
  55.  * destructor, use <code>error_log()</code>, <code>syslog()</code> or
  56.  * something like that instead.
  57.  *
  58.  * @since PHP 4.0.2
  59.  * @author Stig Bakken <ssb@fast.no>
  60.  */
  61. class PEAR
  62. {
  63.     // {{{ properties
  64.  
  65.     var $_debug = false;
  66.     var $_default_error_mode = null;
  67.     var $_default_error_options = null;
  68.     var $_default_error_handler = '';
  69.  
  70.     // }}}
  71.  
  72.     // {{{ constructor
  73.  
  74.     /**
  75.      * Constructor.  Registers this object in
  76.      * $_PEAR_destructor_object_list for destructor emulation if a
  77.      * destructor object exists.
  78.      */
  79.     function PEAR() {
  80.         if (method_exists($this, "_".get_class($this))) {
  81.             global $_PEAR_destructor_object_list;
  82.             $_PEAR_destructor_object_list[] = &$this;
  83.         }
  84.         if ($this->_debug) {
  85.             printf("PEAR constructor called, class=%s\n",
  86.                    get_class($this));
  87.         }
  88.     }
  89.  
  90.     // }}}
  91.     // {{{ destructor
  92.  
  93.     /**
  94.      * Destructor (the emulated type of...).  Does nothing right now,
  95.      * but is included for forward compatibility, so subclass
  96.      * destructors should always call it.
  97.      * 
  98.      * See the note in the class desciption about output from
  99.      * destructors.
  100.      *
  101.      * @access public
  102.      */
  103.     function _PEAR() {
  104.         if ($this->_debug) {
  105.             printf("PEAR destructor called, class=%s\n",
  106.                    get_class($this));
  107.         }
  108.     }
  109.  
  110.     // }}}
  111.     // {{{ isError()
  112.  
  113.     /**
  114.      * Tell whether a value is a PEAR error.
  115.      *
  116.      * @param   $data   the value to test
  117.      * @access  public
  118.      * @return  bool    true if $data is an error
  119.      */
  120.     function isError($data) {
  121.         return (bool)(is_object($data) &&
  122.                       (get_class($data) == "pear_error" ||
  123.                        is_subclass_of($data, "pear_error")));
  124.     }
  125.  
  126.     // }}}
  127.     // {{{ setErrorHandling()
  128.  
  129.     /**
  130.      * Sets how errors generated by this DB object should be handled.
  131.      * Can be invoked both in objects and statically.  If called
  132.      * statically, setErrorHandling sets the default behaviour for all
  133.      * PEAR objects.  If called in an object, setErrorHandling sets
  134.      * the default behaviour for that object.
  135.      *
  136.      * @param $mode int
  137.      *        one of PEAR_ERROR_RETURN, PEAR_ERROR_PRINT,
  138.      *        PEAR_ERROR_TRIGGER, PEAR_ERROR_DIE or
  139.      *        PEAR_ERROR_CALLBACK.
  140.      *
  141.      * @param $options mixed
  142.      *        Ignored unless $mode is PEAR_ERROR_TRIGGER or
  143.      *        PEAR_ERROR_CALLBACK.  When $mode is PEAR_ERROR_TRIGGER,
  144.      *        this parameter is expected to be an integer and one of
  145.      *        E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR.  When
  146.      *        $mode is PEAR_ERROR_CALLBACK, this parameter is expected
  147.      *        to be the callback function or method.  A callback
  148.      *        function is a string with the name of the function, a
  149.      *        callback method is an array of two elements: the element
  150.      *        at index 0 is the object, and the element at index 1 is
  151.      *        the name of the method to call in the object.
  152.      *
  153.      * @see PEAR_ERROR_RETURN
  154.      * @see PEAR_ERROR_PRINT
  155.      * @see PEAR_ERROR_TRIGGER
  156.      * @see PEAR_ERROR_DIE
  157.      * @see PEAR_ERROR_CALLBACK
  158.      *
  159.      * @since PHP 4.0.5
  160.      */
  161.  
  162.     function setErrorHandling($mode, $options = null)
  163.     {
  164.         if (isset($this)) {
  165.             $setmode = &$this->_default_error_mode;
  166.             $setoptions = &$this->_default_error_options;
  167.             $setcallback = &$this->_default_error_callback;
  168.         } else {
  169.             $setmode = &$GLOBALS['_PEAR_default_error_mode'];
  170.             $setoptions = &$GLOBALS['_PEAR_default_error_options'];
  171.             $setcallback = &$GLOBALS['_PEAR_default_error_callback'];
  172.         }
  173.  
  174.         switch ($mode) {
  175.             case PEAR_ERROR_RETURN:
  176.             case PEAR_ERROR_PRINT:
  177.             case PEAR_ERROR_TRIGGER:
  178.             case PEAR_ERROR_DIE:
  179.             case null:
  180.                 $setmode = $mode;
  181.                 $setoptions = $options;
  182.                 break;
  183.  
  184.             case PEAR_ERROR_CALLBACK:
  185.                 $setmode = $mode;
  186.                 if (is_string($options) ||
  187.                     (is_array($options) && sizeof($options) == 2 &&
  188.                      is_object($options[0]) && is_string($options[1]))) {
  189.                     $setcallback = $options;
  190.                 } else {
  191.                     trigger_error("invalid error callback", E_USER_WARNING);
  192.                 }
  193.                 break;
  194.                     
  195.             default:
  196.                 trigger_error("invalid error mode", E_USER_WARNING);
  197.                 break;
  198.         }
  199.     }
  200.  
  201.     // }}}
  202.     // {{{ raiseError()
  203.  
  204.     /**
  205.      * This method is a wrapper that returns an instance of PEAR_Error
  206.      * with this object's default error handling applied.  If the
  207.      * $mode and $options parameters are not specified, the object's
  208.      * defaults are used.
  209.      *
  210.      * @param $message  a text error message
  211.      * @param $code     a numeric error code (it is up to your class
  212.      *                  to define these if you want to use codes)
  213.      * @param $mode     One of PEAR_ERROR_RETURN, PEAR_ERROR_PRINT,
  214.      *                  PEAR_ERROR_TRIGGER, PEAR_ERROR_DIE or
  215.      *                  PEAR_ERROR_CALLBACK.
  216.      * @param $options  If $mode is PEAR_ERROR_TRIGGER, this parameter
  217.      *                  specifies the PHP-internal error level (one of
  218.      *                  E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR).
  219.      *                  If $mode is PEAR_ERROR_CALLBACK, this
  220.      *                  parameter specifies the callback function or
  221.      *                  method.  In other error modes this parameter
  222.      *                  is ignored.
  223.      * @param $userinfo If you need to pass along for example debug
  224.      *                  information, this parameter is meant for that.
  225.      *
  226.      * @return object   a PEAR error object
  227.      *
  228.      * @see PEAR::setErrorHandling
  229.      *
  230.      * @since PHP 4.0.5
  231.      */
  232.  
  233.     function &raiseError($message = null, $code = null, $mode = null,
  234.                          $options = null, $userinfo = null)
  235.     {
  236.         if ($mode === null) {
  237.             $mode = $this->_default_error_mode;
  238.             if ($mode === null) {
  239.                 $mode = $GLOBALS['_PEAR_default_error_mode'];
  240.             }
  241.         }
  242.  
  243.         if ($mode == PEAR_ERROR_TRIGGER && $options === null) {
  244.             $options = $this->_default_error_options;
  245.             if ($options === null) {
  246.                 $options = $GLOBALS['_PEAR_default_error_options'];
  247.             }
  248.         }
  249.  
  250.         if ($mode == PEAR_ERROR_CALLBACK) {
  251.             if (!is_string($options) &&
  252.                 !(is_array($options) && sizeof($options) == 2 &&
  253.                   is_object($options[0]) && is_string($options[1]))) {
  254.                 $options = $this->_default_error_callback;
  255.                 if ($options === null) {
  256.                     $options = $GLOBALS['_PEAR_default_error_callback'];
  257.                 }
  258.             }
  259.         } else {
  260.             if ($options === null) {
  261.                 $options = $this->_default_error_options;
  262.             }
  263.         }
  264.         return new PEAR_Error($message, $code, $mode, $options, $userinfo);
  265.     }
  266.  
  267.     // }}}
  268. }
  269.  
  270. // {{{ _PEAR_call_destructors()
  271.  
  272. function _PEAR_call_destructors() {
  273.     global $_PEAR_destructor_object_list;
  274.     if (is_array($_PEAR_destructor_object_list) && sizeof($_PEAR_destructor_object_list)) {
  275.     reset($_PEAR_destructor_object_list);
  276.     while (list($k, $objref) = each($_PEAR_destructor_object_list)) {
  277.         $destructor = "_".get_class($objref);
  278.         if (method_exists($objref, $destructor)) {
  279.         $objref->$destructor();
  280.         }
  281.     }
  282.     // Empty the object list to ensure that destructors are
  283.     // not called more than once.
  284.     $_PEAR_destructor_object_list = array();
  285.     }
  286. }
  287.  
  288. // }}}
  289.  
  290. class PEAR_Error
  291. {
  292.     // {{{ properties
  293.  
  294.     var $error_message_prefix = '';
  295.     var $error_prepend        = '';
  296.     var $error_append         = '';
  297.     var $mode                 = PEAR_ERROR_RETURN;
  298.     var $level                = E_USER_NOTICE;
  299.     var $code                 = -1;
  300.     var $message              = '';
  301.     var $debuginfo            = '';
  302.  
  303.     // Wait until we have a stack-groping function in PHP.
  304.     //var $file    = '';
  305.     //var $line    = 0;
  306.     
  307.  
  308.     // }}}
  309.     // {{{ constructor
  310.  
  311.     /**
  312.      * PEAR_Error constructor
  313.      *
  314.      * @param $message error message
  315.      *
  316.      * @param $code (optional) error code
  317.      *
  318.      * @param $mode (optional) error mode, one of: PEAR_ERROR_RETURN,
  319.      * PEAR_ERROR_PRINT, PEAR_ERROR_DIE, PEAR_ERROR_TRIGGER or
  320.      * PEAR_ERROR_CALLBACK
  321.      *
  322.      * @param $level (optional) error level, _OR_ in the case of
  323.      * PEAR_ERROR_CALLBACK, the callback function or object/method
  324.      * tuple.
  325.      *
  326.      * @access public
  327.      *
  328.      */
  329.     function PEAR_Error($message = "unknown error", $code = null,
  330.                         $mode = null, $options = null, $userinfo = null)
  331.     {
  332.         if ($mode === null) {
  333.             $mode = PEAR_ERROR_RETURN;
  334.         }
  335.         $this->message   = $message;
  336.         $this->code      = $code;
  337.         $this->mode      = $mode;
  338.         $this->userinfo = $userinfo;
  339.         if ($mode & PEAR_ERROR_CALLBACK) {
  340.             $this->level = E_USER_NOTICE;
  341.             $this->callback = $options;
  342.         } else {
  343.             if ($options === null) {
  344.                 $options = E_USER_NOTICE;
  345.             }
  346.             $this->level = $options;
  347.             $this->callback = null;
  348.         }
  349.         if ($this->mode & PEAR_ERROR_PRINT) {
  350.             print $this->getMessage();
  351.         }
  352.         if ($this->mode & PEAR_ERROR_TRIGGER) {
  353.             trigger_error($this->getMessage(), $this->level);
  354.         }
  355.         if ($this->mode & PEAR_ERROR_DIE) {
  356.             die($this->getMessage());
  357.         }
  358.         if ($this->mode & PEAR_ERROR_CALLBACK) {
  359.             if (is_string($this->callback) && strlen($this->callback)) {
  360.                 call_user_func($this->callback, $this);
  361.             } elseif (is_array($this->callback) &&
  362.                       sizeof($this->callback) == 2 &&
  363.                       is_object($this->callback[0]) &&
  364.                       is_string($this->callback[1]) &&
  365.                       strlen($this->callback[1])) {
  366.                 call_user_method($this->callback[1], $this->callback[0],
  367.                                  $this);
  368.             }
  369.         }
  370.     }
  371.  
  372.     // }}}
  373.     // {{{ getMode()
  374.  
  375.     /**
  376.      * Get the error mode from an error object.
  377.      *
  378.      * @return int error mode
  379.      * @access public
  380.      */
  381.     function getMode() {
  382.         return $this->mode;
  383.     }
  384.  
  385.     // }}}
  386.     // {{{ getCallback()
  387.  
  388.     /**
  389.      * Get the callback function/method from an error object.
  390.      *
  391.      * @return mixed callback function or object/method array
  392.      * @access public
  393.      */
  394.     function getCallback() {
  395.         return $this->callback;
  396.     }
  397.  
  398.     // }}}
  399.     // {{{ getMessage()
  400.  
  401.     
  402.     /**
  403.      * Get the error message from an error object.
  404.      *
  405.      * @return  string  full error message
  406.      * @access public
  407.      */
  408.     function getMessage ()
  409.     {
  410.         return ($this->error_prepend . $this->error_message_prefix .
  411.                 $this->message       . $this->error_append);
  412.     }
  413.     
  414.  
  415.     // }}}
  416.     // {{{ getCode()
  417.     
  418.     /**
  419.      * Get error code from an error object
  420.      *
  421.      * @return int error code
  422.      * @access public
  423.      */
  424.      function getCode()
  425.      {
  426.         return $this->code;
  427.      }
  428.  
  429.     // }}}
  430.     // {{{ getType()
  431.  
  432.     /**
  433.      * Get the name of this error/exception.
  434.      *
  435.      * @return string error/exception name (type)
  436.      * @access public
  437.      */
  438.     function getType ()
  439.     {
  440.         return get_class($this);
  441.     }
  442.  
  443.     // }}}
  444.     // {{{ getUserInfo()
  445.  
  446.     /**
  447.      * Get additional user-supplied information.
  448.      *
  449.      * @return string user-supplied information
  450.      * @access public
  451.      */
  452.     function getUserInfo ()
  453.     {
  454.         return $this->userinfo;
  455.     }
  456.  
  457.     // }}}
  458.     // {{{ getDebugInfo()
  459.  
  460.     /**
  461.      * Get additional debug information supplied by the application.
  462.      *
  463.      * @return string debug information
  464.      * @access public
  465.      */
  466.     function getDebugInfo ()
  467.     {
  468.         return $this->getUserInfo();
  469.     }
  470.  
  471.     // }}}
  472.     // {{{ toString()
  473.  
  474.     /**
  475.      * Make a string representation of this object.
  476.      *
  477.      * @return string a string with an object summary
  478.      * @access public
  479.      */
  480.     function toString() {
  481.         $modes = array();
  482.         $levels = array(E_USER_NOTICE => "notice",
  483.                         E_USER_WARNING => "warning",
  484.                         E_USER_ERROR => "error");
  485.         if ($this->mode & PEAR_ERROR_CALLBACK) {
  486.             if (is_array($this->callback)) {
  487.                 $callback = get_class($this->callback[0]) . "::" .
  488.                     $this->callback[1];
  489.             } else {
  490.                 $callback = $this->callback;
  491.             }
  492.             return sprintf('[%s: message="%s" code=%d mode=callback '.
  493.                            'callback=%s prefix="%s" prepend="%s" append="%s" '.
  494.                            'debug="%s"]',
  495.                            get_class($this), $this->message, $this->code,
  496.                            $callback, $this->error_message_prefix,
  497.                            $this->error_prepend, $this->error_append,
  498.                            $this->debuginfo);
  499.         }
  500.         if ($this->mode & PEAR_ERROR_CALLBACK) {
  501.             $modes[] = "callback";
  502.         }
  503.         if ($this->mode & PEAR_ERROR_PRINT) {
  504.             $modes[] = "print";
  505.         }
  506.         if ($this->mode & PEAR_ERROR_TRIGGER) {
  507.             $modes[] = "trigger";
  508.         }
  509.         if ($this->mode & PEAR_ERROR_DIE) {
  510.             $modes[] = "die";
  511.         }
  512.         if ($this->mode & PEAR_ERROR_RETURN) {
  513.             $modes[] = "return";
  514.         }
  515.         return sprintf('[%s: message="%s" code=%d mode=%s level=%s prefix="%s" '.
  516.                        'prepend="%s" append="%s" debug="%s"]',
  517.                        get_class($this), $this->message, $this->code,
  518.                        implode("|", $modes), $levels[$this->level],
  519.                        $this->error_message_prefix,
  520.                        $this->error_prepend, $this->error_append,
  521.                        $this->debuginfo);
  522.     }
  523.  
  524.     // }}}
  525. }
  526.  
  527. register_shutdown_function("_PEAR_call_destructors");
  528.  
  529. /*
  530.  * Local Variables:
  531.  * mode: c++
  532.  * tab-width: 4
  533.  * c-basic-offset: 4
  534.  * End:
  535.  */
  536. ?>
  537.